.TH MKSHLIB 1 "July 28 2005" "Apple Computer, Inc."
.SH NAME
mkshlib \- create a shared library
.SH SYNOPSIS
.B mkshlib \-s 
.I specfile 
.B \-t 
.I target 
.B \-h 
.I host 
[
.I options
] ...
.SH DESCRIPTION
The 
.I mkshlib
command builds both the host and target shared libraries.  A shared
library is similar in function to a normal, non-shared library,
except that programs that link with a shared library will share the library code
during execution. Programs that link with a non-shared library will get 
their own copies of each library routine used.
.PP
The host shared library is an archive that is used to link-edit user programs
with the shared library (see
.IR ar (5)
).  A host shared library can
be treated exactly like a non-shared library and should be included on
compiler (see
.IR cc (1))
command lines in the usual way.  Furthermore, 
all operations that can be performed on an archive can also be
performed on the host shared library.
.PP
The target shared library is an executable module that is attached to the 
user's process during execution of a program using 
the shared library.  The target shared library contains the code
for all the routines in the library and must be fully resolved.  
The target will be brought into memory during execution of a program
using the shared library, and subsequent processes that use the shared library will share
the copy of code already in memory.  The text of 
the target is always shared, but each process will get its own copy of the 
data.
.PP
The user interface to 
.I mkshilib
consists of command-line options and a shared library specification file.
The shared library specification file describes the 
contents of the shared library.
.PP
The
.I mkshlib
command invokes other tools, such as the assembler,
.IR as (1),
and the link editor,
.IR ld (1).
These tools
are invoked through the use of
.IR execvp (3),
which searches directories
in the user's PATH.
.SH "UNIVERSAL FILE SUPPORT"
.I Mkshlib,
like the link editor, accepts ``universal'' files on input but always creates a
``thin'' host and target shared libraries for only one architecture.  Because of this
.IR mkshlib (1)
only allows one architecture flag,
.BI \-arch " arch_type"
specified at a time.  If no 
.BI \-arch " arch_type"
is specified and the first object file listed in the 
.B #object 
directive is a
``thin'' (standard Mach-O) file then the output shared library architecture
will be that of the first object file.  If the first object is a ``universal''
file then an
.BI \-arch " arch_type"
must be specified. The command 
.IR lipo (1)
must be run explicitly on the results of multiple
.IR mkshlib (1)
executions.
This is unlike the creation of universal executables where the compiler driver
.IR cc (1)
directly runs
.IR lipo (1)
on multiple executions of
.IR ld (1)
to create ``universal'' shared libraries
.PP
The following command line arguments are recognized by
.I mkshlib:
.TP 15
.BI \-arch " arch_type"
Specifies the architecture,
.I arch_type,
selected from the "universal" input files for the output target and host 
shared libraries.  This option must be used when
the first object file listed in the #object directive is a universal file.
Only one 
.BI \-arch " arch_type"
can be specified.  See
.IR arch (3)
for the currently know
.IR arch_type s).
.TP 15
.BI "\-s " specfile
Specifies the shared library specification file,
.I specfile.
This file contains the information necessary to build a shared library.  Its
contents include the branch table specifications for the target,
the pathname in which the target should be installed, the start addresses
of text and data for the target, the initialization specifications for the
host, and the list of object files to be included in the shared library (see
details below).
.TP 15
.BI "\-t " target
Specifies the name,
.I target,
of the target shared library 
produced on the host machine.  When
.I target
is moved to the target machine, it
should be installed at the location given in
the specification file (see the
.B #target
directive below).
.TP 15
.BI "\-h " host
Specifies the name of the host shared library,
.I host.
.TP 15
.B \-v
Sets the verbose option.  This option prints the command lines it executes.
.TP 15
.B \-d
Sets the debugging option.  This option creates a directory ./hostdir and
leaves all the temporary files it creates in there and does not remove them.
.TP 15
.B \-f
Prevents creation of the host library.
.TP 15
.BI \-minor_version " num"
Set the minor version number of the library.  This or the directive
.BI "#minor_version " num
can be used (see below).
.TP 15
.BI \-image_version " num"
Set the minor version number of the target shared library to the
.I num
specified regardless of the value of the minor version.
.TP 15
.BI "\-sectcreate" " segname sectname file"
Creates the section named,
.I sectname 
in the segment named 
.I segname 
from the contents of the file,
.I file.
This section name cannot be the same as a section name in an input object file
in the same segment.  The previous option 
.B "\-segcreate"
will continue to be recognized.  This option is passed to the link editor.
.TP 15
.BI "\-segaddr" " name addr"
Specifies the starting address of the segment named
.I name 
to be
.I addr 
where
.I addr
is a hexadecimal number and must be a multiple of the segment alignment.
.TP 15
.BI "\-segprot" " name max init"
Specifies the maximum and initial virtual memory protection of the segment
named
.I name,
to be
.I max
and
.I init, 
respectively.  The values for
.I max
and
.I init 
are any combination of the characters `r' (for read), `w' (for write),
`x' (for execute) and '\-' (no access).  This option is passed to the link
editor.
.TP 15
.B \-seglinkedit
Passes this flag to the link editor so that the \_\|\_SEGLINKEDIT segment is
produced in the target shared library.
.PP
The shared library specification file contains all the information
necessary to build both the host and target shared libraries.  The
contents and format of the specification file are given
by the following directives:
.TP 15
.BI "#address " "segname address"
Specifies the start address,
.I address,
of the segment
.I segname
for the target. Use this directive to specify the start addresses of
the __TEXT and __DATA segments.  Since the headers are part of the
text segment of a target shared library they are put on their own page.
The real text starts on the next page from where the text segment is specified
with this directive.
.TP 15
.BI "#target " pathname
Specifies the absolute pathname,
.I pathname,
of the target shared library on the target machine.  This pathname is copied to
.B a.out
files and is the location where the operating system will look for
the shared library when executing a file that uses it.
.TP 15
.B #branch
Specifies the start of the branch table specifications.  The lines
following this directive are taken to be branch
table specification lines.
.sp 1
Branch table specification lines have the following format:
.sp 1
.nf
.B
		funcname <white space> position [old_name <old_funcname>]
.r
.sp 1
.fi
where
.I funcname
is the name of the symbol given a branch table entry
and
.I position
specifies the position of
.I funcname's
branch table entry.
.I Position
may be a single integer or a range of integers of the form
.I position1-position2.
Each
.I position
must be greater than or equal to zero, the same position cannot be specified
more than once, and every position from one to the highest
given position must be accounted for.  The special
.I funcname
.I .empty_slot
allocates branch tables slot(s) but put no function in them.  These branch
table slots have an instruction in them that causes an exception.  For the m68k
architecture the instruction is a ``trapl #0xfeadface'', for the m88k
architecture the instruction is an ``illop1'', for the m98k architecture the
instruction is a ``.long 0'', and for the i386 architecture the
instruction is a ``hlt'' instruction.
.sp 1
If a symbol is given more than one branch table entry by associating 
a range of positions with the symbol or by
specifying the same symbol on more than one branch table specification
line, the symbol is defined to have the address
of the highest associated branch table entry.  All other branch table entries
for the symbol can be thought of as ``empty'' slots and can be
replaced by new entries in future versions of the shared library.
.sp 1
When a
.I funcname
changes names from the previous version but otherwise remains compatible, the
branch table slot specification may optionally contain:
.BI old_name " old_funcname"
where
.I old_funcname
was the old name.  The program
.IR cmpshlib (1)
uses this information when it checks branch table slots for compatibility.
.IR cmpshlib (1)
would first check for
.I funcname
matching and then for
.I old_funcname
matching to see if the branch table slot is compatible.
.sp 1
Finally, only functions should be given branch table entries, and
those functions must be external.
.sp 1
This directive can be specified only once per shared library specification file.
.TP 15
.B #objects
Specifies the names of the object files constituting the 
target shared library.  The lines following this directive are taken to
be the list of input object files in the order
they are to be loaded into the target.  The list simply
consists of each file name followed by white space.  This list is also used to 
determine the input object files for the host shared library.
.sp 1
This directive can be specified only once per shared library
specification file.
.TP 15
.BI #filelist " listfile [dirname]"
This is an alternate way of specifing the names of the object files constituting
the target shared library.  The
.I listfile
contains names of object files one to a line separated by newlines (all other
white space is considers part of the object file name).  Optionally, the
directory name,
.I dirname,
is prepended to each object file name (with an added '/' if
.I dirname
does not end in a '/').
If the object file name in the listfile has previously been specified 
in the specification file,  it is ignored.
.sp 1
This directive can be specified more than once but only when the 
.B #objects 
directive is in effect.
.TP 15
.BI "#init " object
Specifies that the object file,
.I object,
requires initialization
code. The lines following this directive are taken to be
initialization specification lines.
.sp 1
Initialization specification lines have the following format:
.sp 1
.nf
.B
		pimport <white space> import
.r
.sp 1
.fi
.I pimport
is a pointer to the associated imported symbol,
.I import,
and must be defined in the current specified object
file,
.I object.
The initialization code generated for each such line can be thought of an
assignment statement of the form:
.sp 1
.nf 
.B
		pimport = &import;
.r
.sp 1
.fi
where
.I pimport
is the absolute address of
.I import.
.sp 1
The
.I import
may no longer be any legal assembly language expression with no white space (for
example _foo+4 is no longer legal after the 1.0 release).
.TP 15
.BI "#minor_version " num
Specifies the decimal number,
.I num, 
as the minor version of the library.
This directive (or the command line option
.B \-minor_version
) must be specified and
.I num
must be greater than zero.  The operating system only allows executables to
execute with minor versions that are equal or less than the shared library
on the system.
.TP 15
.B #private_externs
Specifies a list of external symbols in the library that are not to be included
in the host library.  The lines following this directive are taken to be the
symbol names.  This prevents the user of a library from using these symbols.
.TP 15
.B #nobranch_text
Specifies a list of external text symbols in the library that are not symbol
names of routines but rather
.I const
data.
This prevents
.I mkshlib
from printing a warning, complaining that there are no 
branch table entries for these text symbols.
.TP 15
.B #undefineds
Specifies a list of symbols in the library that are expected to be undefined.
Other symbols that are undefined will cause an error message and the library
will not be built.
.TP 15
.B #alias
Specifies a list of pairs of symbols to ``alias'' to each other using the
.IR ld (1)
.BI \-i definition:indirect
option, automatically causing
.I definition
to be a private extern.
Each of the following lines contains a pair of symbol names on the
same line separated by white space.  The first symbol name on the line is the
.I definition
symbol name and the second is the
.I indirect
symbol name the symbol will become after it is link edited.
.TP 15
\f3##\f1
Specifies a comment.  All information on a line following
this directive is ignored.
.PP
All directives that may be followed by multi-line specifications are
valid until the next directive or the end of the file.
.SH FILES
.nf
mkshlib_*		temporary files
.fi
.SH SEE ALSO
ar(1), as(1), cc(1), ld(1), Mach-O(5), ar(5), ranlib(1), otool(1), arch(3)
